ViRC Whiteboard Interface
Jesse McGrew
June 15, 2001

Introduction
============

ViRC 2's whiteboard is extremely powerful from a scripter's perspective. A
script can create whiteboard windows, draw in them, react to drawing done
either locally or remotely, selectively ignore drawing commands, or change
commands before they are drawn or sent.

Whiteboard windows
==================

Whiteboard windows are similar to DCC chat windows. They have unique numeric
names such as =!5, and non-unique names such as =!Mr2001.

ViRC automatically creates whiteboard windows for DCC whiteboard connections.
Scripts can create them with the $NewWhiteboard() function:

  @ $wboard = $NewWhiteboard($title)

The supplied title will appear in the window's caption, and if it's a single
word it can be used as the window's non-unique name (=!title). The function
returns the window's unique name.

Drawing and manipulating the window
===================================

Commands marked *** are NOT IMPLEMENTED in 2.0pre8. Colors (<pencolor>, <fg>,
etc.) can be given as hex RGB numbers ($bbggrr), their decimal equivalents, or
cl* color constants (clRed, clBlue, etc. - not ecNotice, ecChanText).

Tool types are 0 for pencil, 1 for line, 3 for rectangle, 4 for ellipse, 5 for
filled rectangle, 6 for filled ellipse, 8 for eraser, 9 for flood fill, 10 for
arrow, and 11 for rubber stamp.

Begin recording to a file:
  Whiteboard =!nick record <filename>

End recording:
  Whiteboard =!nick norecord

Play back a recorded file:
  Whiteboard =!nick play <filename>

Save the canvas to a bitmap:
  Whiteboard =!nick save <file.bmp>

Load the canvas from a bitmap:
(note: the loaded bitmap will not be sent over a DCC whiteboard connection)
  Whiteboard =!nick load <file.bmp>

Save the canvas to the clipboard:
  Whiteboard =!nick savetoclipboard

Load the canvas from the clipboard:
(note: see above)
  Whiteboard =!nick loadfromclipboard

Draw with a tool:
  Whiteboard =!nick dr <tooltype> <width> <pencolor> <brushcolor> <x1,y1> <x2,y2>

Clear the canvas:
  Whiteboard =!nick cls

Draw unstyled text in the default font:
  Whiteboard =!nick txt <x,y> <text>

Draw styled text:
(note: <style> is a sum of constants: 1 for bold, 2 for italic, 4 for
 underline, 8 for strikeout)
  Whiteboard =!nick txtex <x,y> <font>,<size> <style> <fg> <bg> <text>

*** Copy a block of canvas:
  Whiteboard =!nick blt <x1src,y1src> <x2src,y2src> <xdest,ydest>
*** Load a rubber stamp image:
  Whiteboard =!nick img <name> <file.bmp>
*** Make a rubber stamp image from a block of the canvas:
  Whiteboard =!nick makeimg <name> <x1,y1> <x2,y2>
*** Set the active tool:
  Whiteboard =!nick settool <tooltype>
*** Set the active rubber stamp:
  Whiteboard =!nick setstamp <name>
*** Begin entering text at a location:
  Whiteboard =!nick entry <x,y>
*** Set a clipping area:
  Whiteboard =!nick clip <x1,y1> <x2,y2>
*** Cancel clipping:
  Whiteboard =!nick noclip

Send a raw drawing command over the DCC connection:
  Whiteboard =!nick send <command>

Simulate a command coming in over DCC:
  Whiteboard =!nick simulate <command>

Resize the canvas:
  Whiteboard =!nick size <width,height>

Reacting to commands
====================

After the local or remote user draws on the whiteboard, the script will be
notified with the events <OnWhiteboardAction> (remote user) or
<OnMyWhiteboardAction> (local user). $0 is the unique window name, $1- is
the command that was processed. Note that these events will not be called
in response to scripted drawing commands.

This command is given in a similar format to the drawing commands above, but
with spaces between parameters changed to commas: DR 1,1,0,0,10,10,50,50

NOCLIP may be reported as SPISPOPD for Doom nostalgia purposes. :)

Trapping commands
=================

When a command has been given by the local or remote user, but before it is
actually drawn or sent, the <OnTrapWhiteboardAction> or
<OnTrapMyWhiteboardAction> events will be fired. As above, $0 is the unique
window name, and $1- is the command.

The local variable $Command will also be set to the command, and the script
can modify it to change the command (or set it to $null to cancel it).

For example, to change ellipses into rectangles and prevent clearing the
canvas:

  Event <OnTrapMyWhiteboardAction_e2r> "% DR 4,*"
    @l $Command = DR 3,$strtokr(, $Command)
  EndEvent

  Event <OnTrapMyWhiteboardAction_nocls> "% CLS"
    @l $Command = $null
  EndEvent